prompt-sync

What is prompt-sync?

The prompt-sync npm package is a simple, synchronous way to get user input from the command line in Node.js applications. It is particularly useful for small scripts and command-line tools where asynchronous input handling is not necessary.

What are prompt-sync's main functionalities?

Basic Input

This feature allows you to prompt the user for input and capture their response synchronously. The example code asks the user for their name and then greets them.

const prompt = require('prompt-sync')();
const name = prompt('What is your name? ');
console.log(`Hello, ${name}!`);

Default Values

You can provide a default value that will be used if the user simply presses Enter without typing anything. The example code asks for the user's favorite color and defaults to 'blue' if no input is provided.

const prompt = require('prompt-sync')();
const color = prompt('What is your favorite color? ', 'blue');
console.log(`Your favorite color is ${color}.`);

Hidden Input

This feature allows you to hide the user's input, which is useful for sensitive information like passwords. The example code prompts the user for a password and masks the input with asterisks.

const prompt = require('prompt-sync')();
const password = prompt('Enter your password: ', {echo: '*'});
console.log('Password received.');

Other packages similar to prompt-sync

readline-sync

The readline-sync package provides similar synchronous input capabilities but with more advanced features like input validation, history, and autocompletion. It is more feature-rich compared to prompt-sync but also slightly more complex to use.

inquirer

Inquirer is a more advanced package for handling user input in command-line applications. It supports asynchronous prompts, multiple types of questions (e.g., lists, checkboxes), and more complex workflows. It is more suitable for larger applications that require more sophisticated user interactions.

README

SYNOPSIS

A sync prompt for node. very simple. no C++ bindings and no bash scripts.

Works on Linux, OS X and Windows.

BASIC MODE

var prompt = require('prompt-sync')();
//
// get input from the user.
//
var n = prompt('How many more times? ');

WITH HISTORY

History is an optional extra, to use simply install the history plugin.

npm install --save prompt-sync-history

var prompt = require('prompt-sync')({
  history: require('prompt-sync-history')() //open history file
});
//get some user input
var input = prompt()
prompt.history.save() //save history back to file

See the prompt-sync-history module for options, or fork it for customized behaviour.

API

require('prompt-sync')(config) => prompt

Returns an instance of the prompt function. Takes config option with the following possible properties

sigint: Default is false. A ^C may be pressed during the input process to abort the text entry. If sigint it false, prompt returns null. If sigint is true the ^C will be handled in the traditional way: as a SIGINT signal causing process to exit with code 130.

eot: Default is false. A ^D pressed as the first character of an input line causes prompt-sync to echo exit and exit the process with code 0.

autocomplete: A completer function that will be called when user enters TAB to allow for autocomplete. It takes a string as an argument an returns an array of strings that are possible matches for completion. An empty array is returned if there are no matches.

history: Takes an object that supplies a "history interface", see prompt-sync-history for an example.

prompt(ask, value, opts)

ask is the label of the prompt, value is the default value in absence of a response.

The opts argument can also be in the first or second parameter position.

Opts can have the following properties

echo: Default is '*'. If set the password will be masked with the specified character. For hidden input, set echo to '' (or use prompt.hide).

autocomplete: Overrides the instance autocomplete function to allow for custom autocompletion of a particular prompt.

value: Same as the value parameter, the default value for the prompt. If opts is in the third position, this property will not overwrite the value parameter.

ask: Sames as the value parameter. The prompt label. If opts is not in the first position, the ask parameter will not be overridden by this property.

prompt.hide(ask)

Convenience method for creating a standard hidden password prompt, this is the same as prompt(ask, {echo: ''})

LINE EDITING

Line editing is enabled in the non-hidden mode. (use up/down arrows for history and backspace and left/right arrows for editing)

History is not set when using hidden mode.

EXAMPLES

  //basic:
  console.log(require('prompt-sync')()('tell me something about yourself: '))

  var prompt = require('prompt-sync')({
    history: require('prompt-sync-history')(),
    autocomplete: complete(['hello1234', 'he', 'hello', 'hello12', 'hello123456']),
    sigint: false
  });

  var value = 'frank';
  var name = prompt('enter name: ', value);
  console.log('enter echo * password');
  var pw = prompt({echo: '*'});
  var pwb = prompt('enter hidden password (or don\'t): ', {echo: '', value: '*pwb default*'})
  var pwc = prompt.hide('enter another hidden password: ')
  var autocompleteTest = prompt('custom autocomplete: ', {
    autocomplete: complete(['bye1234', 'by', 'bye12', 'bye123456'])
  });

  prompt.history.save();

  console.log('\nName: %s\nPassword *: %s\nHidden password: %s\nAnother Hidden password: %s', name, pw, pwb, pwc);
  console.log('autocomplete2: ', autocompleteTest);

  function complete(commands) {
    return function (str) {
      var i;
      var ret = [];
      for (i=0; i< commands.length; i++) {
        if (commands[i].indexOf(str) == 0)
          ret.push(commands[i]);
      }
      return ret;
    };
  };